home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / adoc2140.zip / C.TX_ / C.TX
Text File  |  1994-07-31  |  3KB  |  70 lines
  1. In this example, you should note how the parameter list is handled in
  2. RegexAdd().  Note that for 1-word parameter types, the parameter name
  3. and type can be on the same line.  In this case, the description of the
  4. parameter may also be on the same line.  For multi-word types (such as
  5. unsigned short or char *), the type must appear on the line AFTER
  6. the parameter name.
  7.  
  8. In my code, I use *_EXTFNCT for functions/methods callable from outside
  9. a 'module', *_INTFNCT for functions/methods callable from any place
  10. within a 'module' and *_PRVFNCT for functions/methods that can only be
  11. called within a class/file.
  12.  
  13. // @CHAPTER:REGEX_EXTFNCT
  14. // @FUNCTION    RegexAdd
  15. // @SYNTAX      int RegexAdd( Context, pMatch, pReplace, errContext )
  16. // @DESCRIPTION This function compiles the match regular expression and, if
  17. //              successful, adds a new element to the context.
  18. // @PARAM       Context     REGEXCONTEXT
  19. //              An initialized regular expression context into which the
  20. //              new element is to be added.
  21. // @PARAM       pMatch
  22. //              char *
  23. //              Address of NULL-terminated string defining the match
  24. //              regular expression.
  25. // @PARAM       pReplace
  26. //              char *
  27. //              Address of NULL-terminated string defining the replace
  28. //              regular expression.
  29. // @PARAM       errContext      ERRORCONTEXT        Error stack context
  30. //              into which error information is placed.
  31. // @RETURNS     0 if successful otherwise an error code as defined in
  32. //              regex.h
  33. // @INCLUDES    include/regex.h
  34. // @FILE        regex/funcs.c
  35. // @END
  36.  
  37.  
  38. The following example shows how you can document C type declarations.
  39.  
  40. // @CHAPTER:DATA
  41. // @STRUCTURE       RECT
  42. // @DESCRIPTION     This structure is from the Windows SDK and is used to
  43. //                  specify a rectangular region in a 2-dimensional space.
  44. // @DEFINITION      typedef struct tagRECT
  45. //                  {
  46. //                 \    int left;
  47. //                 \    int top;
  48. //                 \    int right;
  49. //                 \    int bottom;
  50. //                  } RECT;
  51. // @MEMBERDATA      left        int     Coordinate of left of rectangle.
  52. // @MEMBERDATA      top         int     Coordinate of top of rectangle.
  53. // @MEMBERDATA      right       int     Coordinate of right of rectangle.
  54. // @MEMBERDATA      bottom      int     Coordinate of bottom of rectangle.
  55. // @INCLUDES        windows.h
  56. // @END
  57.  
  58.  
  59. This example shows that C #defines can be documented in a manner that is very
  60. similar to the data type documentation.
  61.  
  62. // @CHAPTER:DATA
  63. // @MACRO           HIWORD
  64. // @DEFINITION      #define HIWORD(l)
  65. //                         ((WORD)((((DWORD)(l)) >> 16) & 0xFFFF))
  66. // @DESCRIPTION     This macro returns bits 15 through 31 of the given
  67. //                  4-byte value as a 2-byte value.
  68. // @INCLUDE         windows.h
  69. // @END
  70.